The typical sequence for running the MockServer docker image is as follows:

<ol>
	<li><a href="#install_docker">Install Docker</a></li>
	<li><a href="#pull_docker_image">Pull (or Update) Image</a></li>
	<li><a href="#run_docker_container">Run Container</a></li>
</ol>

In addition it is possible to <a href="#docker_container_customization">customise how the container is run</a>.

<a id="install_docker" class="anchor" href="#install_docker">&nbsp;</a>

<h3>Install Docker</h3>

<p>To install Docker see the <a href="https://docs.docker.com/installation/">installation instructions</a>.</p>

<a id="pull_docker_image" class="anchor" href="#pull_docker_image">&nbsp;</a>

<h3>Pull MockServer Image</h3>

<p>To pull the MockServer Docker image use the pull command, as follows:</p>

<pre><code class="code">docker pull mockserver/mockserver</code></pre>

<p>This is not strictly necessary as the image will be automatically pulled if it does not exist when the run command is used. However, using the pull command will ensure the latest version of the image is downloaded.</p>

<a id="run_docker_container" class="anchor" href="#run_docker_container">&nbsp;</a>

<h3>Run MockServer Container</h3>

<p>Then to run MockServer as a Docker container run the following command:</p>

<pre><code class="code">docker run -d --rm -P mockserver/mockserver</code></pre>

<p>The <strong>-P</strong> switch in this command tells Docker to map all ports exported by the MockServer container to dynamically allocated ports on the host machine.</p><p>To view information about the MockServer container, including which dynamic ports have been used run the following command:</p>

<pre><code class="code">docker ps</code></pre>

<a id="docker_container_customization" class="anchor" href="#docker_container_customization">&nbsp;</a>

<h3>Configure Port Mapping</h3>

<p>This MockServer docker container exports the following port:</p>

<ul>
	<li><strong>serverPort</strong> 1080</li>
</ul>

<p>To specify which ports (on the host machine) should be mapped to the MockServer docker container use the <strong>-p</strong> <span class="command_line_argument_placeholder">&lt;host port&gt;</span><strong>:</strong><span class="command_line_argument_placeholder">&lt;container port&gt;</span> option, as follows:</p>

<pre><code class="code">docker run -d --rm -p <span class="command_line_argument_placeholder">&lt;serverPort&gt;</span>:<span class="numeric_literal">1080</span> mockserver/mockserver</code></pre>

<p>For example:</p>

<pre><code class="code">docker run -d --rm -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span> mockserver/mockserver</code></pre>

<h3>Modifying Default Command</h3>

<p>By default when the MockServer container runs it executes a bash script passing three command line options, as follows</p>

<pre><code class="code">-logLevel <span class="string_literal">INFO</span> -serverPort <span class="numeric_literal">1080</span></code></pre>

<p>This can be modified to change the command line options passed to the MockServer for example:</p>

<pre><code class="code">docker run --rm --name mockserver -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1090</span> mockserver/mockserver <em>-logLevel <span class="string_literal">INFO</span> -serverPort <span class="numeric_literal">1090</span> -proxyRemotePort <span class="numeric_literal">443</span> -proxyRemoteHost <span class="string_literal">mock-server.com</span></em></code></pre>

<h3>Interactive Shell</h3>

<p>MockServer uses <a href="https://github.com/GoogleContainerTools/distroless">distroless</a> as its based container for both size and security and so does not contain an interactive shell.  This minimises the likelihood of vulnerabilities and to reduces the attack surface by ensuring only the JVM and MockServer code is inside the container.</p>

<a id="docker_detailed_configuration" class="anchor" href="#docker_detailed_configuration">&nbsp;</a>

<h2>Detailed MockServer Configuration</h2>

<p>To support configuring MockServer a <strong>mockserver.properties</strong> will be loaded from <strong>/config</strong> directory if it exists.</p>
<p>A <strong>mockserver.properties</strong> configuration file and other related configuration files such as <a href="/mock_server/initializing_expectations.html">json expectation initialization</a>, or custom <a href="/mock_server/HTTPS_TLS.html#configuration">TLS CA, X.509 Certificate or Private Key</a> should be mapping into the <strong>/config</strong> directory.</p>

For example to add configuration files in the current directory, such as <strong>mockserver.properties</strong>, map <strong>$(pwd)</strong> into <strong>/config</strong>, as follows:

<pre><code class="code">docker run -v $(pwd):/config -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span>  mockserver/mockserver -serverPort <span class="numeric_literal">1080</span></code></pre>

<p>See <a href="/mock_server/configuration_properties.html">MockServer Configuration</a> for details of all configuration options.</p>

As the <a href="https://github.com/mock-server/mockserver/blob/master/docker/Dockerfile">Docker image is based from <strong>gcr.io/distroless/java:11</strong></a> and the user <strong>nonroot</strong> is used, we need to configure permissions in order to allow the user in the container read/write files in mounted volumes:

<pre><code class="code">chmod o+r $(pwd)/mockserver.properties</code></pre>

<a id="docker_extend_classpath" class="anchor" href="#docker_extend_classpath">&nbsp;</a>

<h2>Extending MockServer Classpath</h2>

<p>To use <a href="/mock_server/creating_expectations.html#button_response_class_callback">class callbacks</a> or an <a href="/mock_server/initializing_expectations.html#expectation_initializer_class">expectation initializer class</a> the classpath for MockServer must include the specified classes.</p>
<p>To support adding classes to the classpath any jar files contained in the <strong>/libs</strong> directory will be added into MockServer classpath.</p>

For example to add all jar files in the current directory, map <strong>$(pwd)</strong> into <strong>/libs</strong>, as follows:

<pre><code class="code">docker run -v $(pwd):/libs -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span>  mockserver/mockserver -serverPort <span class="numeric_literal">1080</span></code></pre>

<a id="docker_compose" class="anchor" href="#docker_compose">&nbsp;</a>

<h2>Docker Compose</h2>

<p>MockServer can be run using <a href="https://docs.docker.com/compose/">docker compose</a> by adding the container as a service.</p>

<p>The MockServer container uses an <span class="keyword">entrypoint</span>, so it is possible to configure the MockServer by specifying the command line flags using by specifying the <span class="keyword">command</span>, as follows:</p>

<pre class="prettyprint lang-java code"><code class="code">version: "2.4"
services:
  mockServer:
    image: mockserver/mockserver:mockserver-5.11.2
    command: -logLevel DEBUG -serverPort 1090 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com
    ports:
      - 1080:1090</code></pre>

<p>It is also possible to configure the MockServer by setting <span class="keyword">environment</span> variables, as follows:</p>

<pre class="prettyprint lang-java code"><code class="code">version: "2.4"
services:
  mockServer:
    image: mockserver/mockserver:mockserver-5.11.2
    ports:
      - 1080:1090
    environment:
      MOCKSERVER_MAX_EXPECTATIONS: 100
      MOCKSERVER_MAX_HEADER_SIZE: 8192</code></pre>

<p>It is also possible to configure the MockServer by mounting a volume containing a properties file or JSON expectation initializer, as follows:</p>

<pre class="prettyprint lang-java code"><code class="code">version: "2.4"
services:
  mockServer:
    image: mockserver/mockserver:mockserver-5.11.2
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_PROPERTY_FILE: /config/mockserver.properties
      MOCKSERVER_INITIALIZATION_JSON_PATH: /config/initializerJson.json
    volumes:
      - type: bind
        source: .
        target: /config</code></pre>
